Page Comparison

his serves as a list of pages that need work, each page is labelled according to what stage it is in.

For information on how to write documentation, please refer to the Style Guide.

Labels: ok, in_progress, unfinished, needs_update, create_content, delete.

delete: This page is likely to be deprecated but needs review before being deleted.

create_content: This page is a stub or missing content entirely, a placeholder for a page that needs to be written.

unfinished: This page has content but is not considered functional.

in_progress: This page is functional but incomplete.

needs_update: This page is possibly out of date and needs review by someone knowledgable on the subject.

ok: Someone knowledgable on the subject has signed off on this page's accuracy.

The following tags are proposed for content tagging and navigation, July 2020:

Proposal:

Each document will have the following labels:

1 content type label

1+ tech labels

1+ hysds specific labels

1+ content variables label

1 ?? housekeeping

1 SME label

= total of at least 6 labels

BOLD = used in wiki

NOT BOLD = proposed but not yet applied to anything in the wiki

7/13: Spencer tag up feedback: Prerequisite box (via Content by Label macro) along top of article populated by potential “implicit technologies” and/or “access/permissions requirements”

Note: the prerequisite content doesn’t always need to be label-based and pointing to wiki docs.

TODO: per Lan, structure tags in a table format for horizontal viewing.

Style Guide vs Doc Development Guide:

feedback from meetup:

Goal: doc development guide will help getting the wiki organized so that it can transition to maintenance mode.

Per doc community, the style guide:

• it gives a set of rules or guidelines for how to write your docs. One point: define a word list, so the same words are used in the same way. Project specific word lists which can include hysds specific terms or technical terms but has one specific meaning in terms of hysds context

• speak with a uniform voice. the documents should all sound like they're written by the same person

• "Linting text", see an example: https://github.com/get-alex/alex  TODO: research linters and see if it can be incorporated into workflow (TODO: follow up with Lan about using confluence API for linting)

• https://www.writethedocs.org/guide/writing/style-guides/

Doc Development Guide:

• Goal: figure out how to organize all of the content

• Discoverable, eliminate confusing/incorrect docs, identifying needed onboarding docs

• How to put together onboarding docs.

Top priority articles:

Contribution Guide, Community Roadmap, FAQ, Style Guide.

Any given page should only have one of these labels. If you feel, after reviewing a page, that it is labeled inaccurately, change the label. Be sure to remove the old label.

Click any of these links to be taken to a list of pages with that label.

(if the page is not found or there is nothing listed under the link, there are no pages with that label.)

Delete

Create Content

Unfinished

In Progress

Needs Update

OK