mDuo13/devportal-reorg-guidelines.md

## devportal-reorg-guidelines.md

      
    Raw
  

              devportal-reorg-guidelines.md
            
          
    Dev Portal Reorg Guidelines (2018-05)

The Mind Map shows the layout of pages. Most nodes have either a link to the original content or an exclamation-point marker indicating that the content does not yet exist. Each node in the mind map represents one "Page" in Dactyl terminology. The dev portal has only one "target" at the moment, called "local" and all pages should belong to that target.
When you start a reorg task, begin with the latest copy of ripple-dev-portal's master branch (be sure to pull first!) and create a branch from there.
The reorg tasks include:

moving and renaming existing files (mostly done already).
splitting up content from old files into new files, or (rarely) combining content from several old files into one new file.
reformatting page content to fit its new place.
adding the files to the dactyl-config.yml file.

When you think you are almost done, make sure that dactyl_build successfully builds the site. If it doesn't, you probably have either a missing include (TemplateNotFound error) or a typo'd file name in the dactyl-config.yml file (could be a missing file or a redundant file).
If you've done all of the above for one chunk of pages, open a pull request back to the ripple-dev-portal master branch with your changes.
The reorg DOES NOT include:

rewriting docs to fit their intended doc type (for example, making "tutorials" more tutorial-like) or otherwise substantively updating their content. Fixing typos is OK.
creating docs that are listed in the mind map but do not have source content
porting content from non-dev-portal sources such as the wiki or the dev blog
fixing all links in content (except tasks specifically for fixing links). Fixing a few broken links in the files you're moving is OK.

In more detail:
1. Moving and Renaming

The name of each node in the Mind Map shows the intended title of each page. The title should be in a h1 with no other formatting, followed by a blank line. For example:
# The rippled Server

lorem ipsum dolor sit amet

Avoid "XRP Ledger" in page titles. The entire website is "XRP Ledger"-related, so repeating it is needlessly redundant and possibly even confusing.
There should be no backticks even when the page title includes words or names that would ordinarily be in code font such as rippled.
The markdown file name should match the header, except all lowercase and with dashes instead of spaces, and ending in .md of course. The filename should include all words from the title, even intervening/unimportant words like "a" and "the". The file name should only include underscores if they represent literal underscores, for example in method names. The file name should drop other punctuation except periods in literal file names. (For example, ripple.cfg-reference.md would be OK.) The HTML file name (see step 4, adding content to dactyl-config.yml) will match the markdown file name except with .html instead of .md.
Non-page files

The dev portal content includes several files that do not directly represent pages, including:

snippets (_snippets/ folder)
source files for images (_img-sources/ folder)
code samples (_code-samples/ folder)

All such files should be saved in the corresponding folder, which is prefixed with an underscore. Sub-folders do not need to be underscore-prefixed, nor do files within those folders.
2. Splitting Up and Combining Files

The repo has several files ending in -old-monolith.md. These files are the large old references that are being split up. The goal is that, by the end of the reorg, these files will be empty and can be deleted.
As you move content from a "monolith" file into its new location, delete the content from the monolith. To avoid merge conflicts, do not edit any other part of the monolith file.
Adjust header names and levels of new files as appropriate for the new content. Avoid wholesale rewriting of content.
3. Reformatting pages to fit their new place


adjust the header levels so that every page starts with an h1 and has no other h1's, then each header down the list
include any necessary "common" link definition snippets. Many of these were included once in the monolith pages and now need to be included separately in each stand-alone page.

The link snippets you may care about:


Path
Description


_snippets/tx-type-links.md
Has definitions for transaction type links like OfferCreate transaction][] and [AccountSet][].


_snippets/rippled-api-links.md
Has definitions of various links commonly appearing in the rippled APIs like [drops of XRP][], [base58][], [Marker][], and [Interledger Protocol][] as well as definitions of rippled API methods like [account_lines method][]. Unlike the common format these docs used to use for API method links, the rippled API methods don't use backticks on the method name (because of Python-Markdown/markdown#495 ). If you spot links that could be changed to use these references, please change them.


_snippets/rippled_versions.md
(I should probably change that filename to use a hyphen instead of an underscore. Oh well, later.)


4. Adding files to dactyl-config.yml

There should be # TODO: placeholders for everything in the mind map (some of them are just groups like # TODO: 5 other ledger methods). As you add files, remove the TODO markers for the files you've added. If some of the TODO pages in your section represent content that either doesn't exist or isn't currently sourced from a markdown file in the dev portal, leave TODO markers for those pages, preferably with ticket numbers for the task to follow up and create/migrate that content.
Most pages should have a dactyl-config.yml entry that looks like one of these examples:
-   md: references/rippled-api/public-rippled-methods/ledger-methods/ledger.md
    html: ledger.html
    funnel: Docs
    doc_type: References
    supercategory: rippled API
    category: Public rippled Methods
    subcategory: Ledger Methods
    targets:
        - local
        
-   name: Key Generation Methods #TODO: possible md landing content?
    html: key-generation-methods.html
    funnel: Docs
    doc_type: References
    supercategory: rippled API
    category: Public rippled Methods
    subcategory: Key Generation Methods
    template: template-landing-children.html
    blurb: Use these methods to generate cryptographic keys.
    targets:
        - local

Notes by field:


Field
Description


md
The path, under content/, of the markdown file this page represents.


name
Human-readable title of the page. Only include this field if there's not a md source for this page (generally just for landing pages or placeholders).


html
The unique HTML filename where this page gets written. Should be the same as the markdown filename but with .html instead of .md and not including the whole path. If you end up with two files that have the same exact filename, raise the issue in #docs-private in Slack and we'll come up with an exception.


funnel
Almost always Docs. If you forget this or make a typo, the page may not show up in navigation lists.


doc_type
Either Concepts, Tutorials, or References (sorted in that order). Must be plural. If you forget this or make a typo, the page may not appear in navigation where you expect it to.


supercategory
Omit except for pages under rippled API.


category
Everything under Docs should have a category. The parent/landing page for a category must be the first page to have that category and it should have a title that matches the category exactly. A category is an expandable/collapsible segment of the side menu (unless it has only one page). If you make a typo, you may get an extra category in the sidebar and the category title may go to a different page than you expect.


subcategory
The parent of a given subcategory must be the first page to have that subcategory value. All following pages that have the subcategory will appear indented in the side navigation.


template
Omit this on leaf pages. On parent pages, you can use template: template-landing-children.html to get an automatic display of child pages after the central content. Code tabs currently don't work on pages using that template, though. (If code tabs look broken on, say, an API method page, you probably used this template by accident.)


blurb
Optional brief description of a page. Be careful of clashes with YAML syntax in this sentence (: and # are particularly dangerous). If this page's parent uses template: template-landing-children.html, this blurb will appear under the page name. Some landing pages also reference the blurbs of various pages in card displays. If the page doesn't have a markdown source file, the template-landing-children.html template may also use this blurb in place of body content (it doesn't at time of this writing, but that's the plan).
Path	Description
`_snippets/tx-type-links.md`	Has definitions for transaction type links like `OfferCreate transaction][]` and `[AccountSet][]`.
`_snippets/rippled-api-links.md`	Has definitions of various links commonly appearing in the rippled APIs like `[drops of XRP][]`, `[base58][]`, `[Marker][]`, and `[Interledger Protocol][]` as well as definitions of rippled API methods like `[account_lines method][]`. Unlike the common format these docs used to use for API method links, the rippled API methods don't use backticks on the method name (because of Python-Markdown/markdown#495 ). If you spot links that could be changed to use these references, please change them.
`_snippets/rippled_versions.md`	(I should probably change that filename to use a hyphen instead of an underscore. Oh well, later.)
Field	Description
`md`	The path, under `content/`, of the markdown file this page represents.
`name`	Human-readable title of the page. Only include this field if there's not a `md` source for this page (generally just for landing pages or placeholders).
`html`	The unique HTML filename where this page gets written. Should be the same as the markdown filename but with `.html` instead of `.md` and not including the whole path. If you end up with two files that have the same exact filename, raise the issue in #docs-private in Slack and we'll come up with an exception.
`funnel`	Almost always `Docs`. If you forget this or make a typo, the page may not show up in navigation lists.
`doc_type`	Either `Concepts`, `Tutorials`, or `References` (sorted in that order). Must be plural. If you forget this or make a typo, the page may not appear in navigation where you expect it to.
`supercategory`	Omit except for pages under `rippled API`.
`category`	Everything under `Docs` should have a category. The parent/landing page for a category must be the first page to have that category and it should have a title that matches the category exactly. A category is an expandable/collapsible segment of the side menu (unless it has only one page). If you make a typo, you may get an extra category in the sidebar and the category title may go to a different page than you expect.
`subcategory`	The parent of a given subcategory must be the first page to have that subcategory value. All following pages that have the subcategory will appear indented in the side navigation.
`template`	Omit this on leaf pages. On parent pages, you can use `template: template-landing-children.html` to get an automatic display of child pages after the central content. Code tabs currently don't work on pages using that template, though. (If code tabs look broken on, say, an API method page, you probably used this template by accident.)
`blurb`	Optional brief description of a page. Be careful of clashes with YAML syntax in this sentence (`:` and `#` are particularly dangerous). If this page's parent uses `template: template-landing-children.html`, this blurb will appear under the page name. Some landing pages also reference the blurbs of various pages in card displays. If the page doesn't have a markdown source file, the `template-landing-children.html` template may also use this blurb in place of body content (it doesn't at time of this writing, but that's the plan).