Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use a Wiki instead of a document #2

Open
NickStavros opened this issue Jan 14, 2022 · 0 comments
Open

Use a Wiki instead of a document #2

NickStavros opened this issue Jan 14, 2022 · 0 comments

Comments

@NickStavros
Copy link

I think what has been provided is good, but it mixes definitions with encyclopedia type of explanations. Both are good, but both are not glossary entries. I think you also need to add references, standards, user scenarios, architectures, FAQ, "How To" Guides, " etc.

Look at the Glossary for the OMG DIDO-RA:

https://www.omgwiki.org/dido/doku.php?id=dido:public:ra:xapend:xapend.a_glossary:start

This allows

  • Each term to be developed and maintained independent of the entire document
  • Each term as a clean URI that points directly to the term for use in other documents and by the wider community
  • Each term can have a discussion section
  • There can be different templates for each kind of term that has the boilerplate provided for that term
  • There can be private and a public area of the glossary. Terms that are "approved" can move from private to public
  • Public terms are searchable by search engines, making them more likely to be used by outside groups
  • It is easy to link definitions together to make a more natural web experience
  • Every version of every term is kept and can be referred to for historical reasons
  • Using the automatic backlink tracing capability allows for a good review when terms need to be updated/modified to ensure you don't break other things during the upgrade process.
  • You can de-conflict overloaded terms

If you are interested, I would be glad to help with this using the OMG wiki structure as seen in DIDO-RA

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant