haarer
commented
1 month ago Christian, i like the idea in the ppt, looking like documentation building blocks, and possibly a journey thru them. (if i misunderstood, pls clarify)
I also agree to the Idea to rebalance the Documentation. I have an other concern about the documentation - its "look" We were up to now happy with the plain markdown approach but i believe we can do better. An Idea could be to change the documentation to a jekyll based generator scheme like oskar has done it for the cocoml repo which generates to a nice looking page But perhaps that should be separated entirely.
Below i am trying to collect, which reasons to look into the documentation some one might have. If we agee on these, then we could optimize the documentation building blocks for these "user stories" in a further step.
- Just attempting to get an overview about SAF : "what's that SAF my Collegue mentionend" -> the best result would be if the visitor has this overvie and ideally tells others it is interesting and comes back
- Want to try SAF : "what do i need to try SAF and how to should i begin" -> best result: visitor is able to quickly download and install one of the implementations, and starts modeling with saf
- Using SAF, selecting viewpoints: "which viewpoints should i select for a problem at hand"
- Using SAF, working on viewpoints: "how do i use this specific viewpoint"
- Using SAF, wanting help: "who can help me with a question"
- Using SAF, missing a Feature: "how can i propose to have a feature added"
- Wanting to Contribute: "how can i help developint"
- Wanting to extend : "how can i add company or domain specific viewpoints"
- Developing SAF: "how do i work on the SAF specification
This is a bit similar to the Use Cases Idea in the development documentation. But there has not yet been any discussion what to prioritize.
There are currently the following markdown files covering "hand written" developement descriptions
- saf-dev-guideline.md this is a bit "work flowish" with some intro and a part covering an exported file, which doesnt really fit in
- development.md
this is a wild mix of
- definitions (which kinds of model do we have, what is in the concept model, what are concerns etc. )
- the way we document saf for which use case
- an index to the development documentation
- modelguideline.md this is about the modeling conventions of the specification model .
Additionally there are (but they are fully generated from the model)
- metrics
- concept model diagrams
- developement documentation pages views for each viewpoint
clalitsc
Is the user looking for all content on the SAF-Specification start page in the current thematic breadth? Is the information on SAF releases and tool implementations so relevant for the user that it has to be managed in such a representative way on the SAF-Specification start page? Isn't it possible to manage the less important information on Github SAF-specification subpages in a more suitable form? So, balancing depth and breath addressing information needs? SAF-Specification GitHub Wegweiser.pptx