search

odpi / egeria-docs

Documentation repository for the Egeria project.
https://egeria-project.org
Other
22 stars 30 forks source link

Migrate Types documentation #28

Open cmgrote opened 3 years ago

cmgrote commented 3 years ago

There's a reasonable chunk of work to do regarding migrating the Types documentation. The tasks would involve:

Naturally follow the documentation guide as part of the updates (remove the license footers from each page, retain the license headers, ensure appropriate use of capitalization vs italics and bold, etc).

The base model (area 0) has been migrated already according to these principles as a starting point -- only 6 more areas to go! 😬

(For reference, here's the "example of 'good'" in the repo itself: https://github.com/odpi/egeria-docs/tree/main/site/docs/types/0, with this being the output: https://odpi.github.io/egeria-docs/types/0/0010-base-model/)

adinh808 commented 3 years ago

@cmgrote Can I work on this?

cmgrote commented 3 years ago

@adinh808 that would be amazing, thank you! Do let me know if you have any questions as you go -- happy to respond either here in the issue, or if you want to put in a draft PR with an initial page or two for me to look at to review and provide comments against that might be even better.

adinh808 commented 3 years ago

@cmgrote Thanks for assigning the Issue. As you mentioned, I will update for one page and based on that you can provide your comments. I will do this update by weekend.

adinh808 commented 3 years ago

@cmgrote For the first two points, Are we taking input from Egeria old site? From where should I take the images as I don't see content inside further types (0,1,2..). I can convert the image files and update the content but from where should I take the content?

cmgrote commented 3 years ago

Yes, take the core Egeria repo as the source -- type details are all under open-metadata-publication/website/open-metadata-types

If I recall there is one draw.io file per area, which has many tabs within it -- basically one tab per page of the site. So basically it means saving the diagram in each tab as a new separate SVG file (+ embedded diagram, as detailed in the guide).

adinh808 commented 3 years ago

@cmgrote I have created a Draft PR for review, https://github.com/odpi/egeria-docs/pull/39 Please check and comment so that I can proceed further

adinh808 commented 3 years ago

@cmgrote Thanks for the detailed Instructions for PR 39 How should we go ahead now? One single PR for all the Types or what's your plan?

adinh808 commented 3 years ago

@cmgrote I have just mapped my Github profile again to IBM ID. So I will be using, adinhtdsibm for further updates in documentation.

cmgrote commented 3 years ago

I'm fine with multiple smaller PRs, but don't really mind either way -- whichever you prefer.

adinhtdsibm commented 3 years ago

@cmgrote Thanks for the update. I will start working on it. Will start with Types and use one PR to complete this task.

adinhtdsibm commented 3 years ago

@cmgrote Could you please assign it back to my ID, adinhtdsibm ? I have started working on this and will update you at the earliest.

adinhtdsibm commented 3 years ago

@cmgrote Quick question on Formatting.

I have checked this link, https://odpi.github.io/egeria-docs/guides/documentation/formatting/#use-italics-to-emphasize-new-terms where it mentioned to use Italics for new words rather bold.

In Type 1 files, I could see many are in Bold, should I convert to Italics? Ex: Peers to Peer ? I am referring to this page, https://egeria.odpi.org/open-metadata-publication/website/open-metadata-types/0112-People.html as there are many "Bold" types.

I have completed Area 1 and will submit a PR for this alone to see if I followed all the tasks. I will target to complete by this weekend and mostly will submit 2-3 PR's as Type 5 is huge.

cmgrote commented 3 years ago

Yes, italics please -- no worries on multiple PRs

adinhtdsibm commented 3 years ago

@cmgrote Raised a Pull request for Area 1 and Area 2 Types migration from egeria site. https://github.com/odpi/egeria-docs/pull/44

Following are migrated, Area 1 https://egeria.odpi.org/open-metadata-publication/website/open-metadata-types/Area-1-models.html Area 2 https://egeria.odpi.org/open-metadata-publication/website/open-metadata-types/Area-2-models.html

Following images are not present in Area2 draw.io file so used Inkscape to convert to svg type. 0211-Data-Sets.png 0220-Files-and-Folders-Example.png 0265-Analytics-Assets.png

adinhtdsibm commented 3 years ago

@cmgrote Upon your review for PR #44 I will commit the other completed ones, Area 3 and Area 4 Types.

adinhtdsibm commented 3 years ago

@cmgrote Any update on this? Apologies to disturb you frequently on this. If you can complete this review, rest of the Area Types migration can be completed.

cmgrote commented 3 years ago

@adinhtdsibm apologies -- was completely offline on holiday the past week... taking a look now.

adinhtdsibm commented 2 years ago

@cmgrote - I have created a PR #50 specific to Area 1 documentation only and closed the existing PR as somehow the push was not at all working and had issues with my VM so created a new PR and added content only for Area 1.

Following are the changes that you requested earlier,

  1. Every markdown file should have at least one (more likely several) sub-headings at the ## level: one for every new entity or relationship that is defined in the UML diagram. If there is no existing description, have a look in the OpenMetadataTypesArchive Java source files for the type definition itself -- there will at least be a description of the entity / relationship that you can use as a starting point for now.
    1. Anytime the name of a type is used it should have no spaces and should be back-ticked, unless it is being used in the description of the type itself, in which case it should be italicised rather than back-ticked (but still should not have any spaces).
    2. When linking to other types that are defined on other markdown pages, include a direct link to that type using a URL like the following: /egeria-docs/types/n/0nxx/abc/#typename, where n is the area number, xx is the numeric model within the area, abc is the name of the markdown file (without any extension), and #typename is the name of the type (all lower-case, no spaces, no hyphens and always just a single # irrespective of the level of the heading) -- this direct-linking is the reason for that first bullet (ensuring every type that is defined has a heading: it's this heading that we're linking to).
    3. These should link the type name directly to the sub-heading rather than referring to the numeric model more generally, and the name of the type should be given exactly (without spaces) and back-ticked.
    4. Changes to Type name for files, 0112-people.md & 0110-actors.md

Please do review and let me know if there are any other updates to be done.

adinhtdsibm commented 2 years ago

@cmgrote @mandy-chessell I am going with Area Type 2 and other Types migration. Do you have any action items or any updates that I need to take care of?

adinhtdsibm commented 2 years ago

@cmgrote I will be working on this Documentation from tomorrow as I had a TP issue where all my data was erased. Please do let me know if there any updates in between that I need to take care of.

mandy-chessell commented 2 years ago

All of the type definitions are migrated to the new site in pretty much their original form - I expect they still contain broken links and the fomatting could be improved.

In fact the biggest problem we still have is broken links all over the site. Any help there would be appreciated.

adinhtdsibm commented 2 years ago

@mandy-chessell Ok sure. Will verify the broken links.

adinhtdsibm commented 2 years ago

@mandy-chessell Updated Type Area 7 and will proceed to update broken links for other Types.