Page MenuHomeSoftware Heritage

Write user stories entering the SWH world and its documentation
Open, NormalPublic

Description

The SWH world is vast and newcomers have different entry points to understand it and contribute to it.
With a couple of user stories we can improve the documentation structure and inter-linking.

  • wiki
  • dev-doc
  • the forge
  • mailing lists
  • website
    • guidelines
    • articles
  • archive

All have very valuable information.

This can be also useful for a Google Season of Docs or an external writer.

The template can be :

As <who> <when> <where>, I <want> because <why>

For example:

whowhenactionwhywhere documented nowwhere should beprovided by
a researcherpublishing an articlesave my repo in the SWH archiveto make it citablein the website guidelines?MG

Event Timeline

moranegg renamed this task from Write user stories entering the SWH world its documentation to Write user stories entering the SWH world and its documentation .Nov 14 2019, 11:37 AM
moranegg triaged this task as Wishlist priority.
moranegg created this task.
moranegg raised the priority of this task from Wishlist to Normal.
moranegg updated the task description. (Show Details)
moranegg added a subscriber: douardda.

This list of user stories is something that can be written in a wiki.
@douardda or do you prefer having this list of scenarios in the docs ( for example in: docs.softwareheritage.org/user-stories)

A summary of the following article:
https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f

Product documentation
Process documentation

Product documentation

Product documentation describes the product that is being developed and provides instructions on how to perform various tasks with it. Product documentation can be broken down into:

System documentation and
User documentation
  1. System documentation :
    • requirements documents: the system functionality (business rules, user stories, use cases, product’s purpose, its features, functionalities, and behavior)
    • design decisions,
    • architecture descriptions,
    • program source code,
    • and help guides.
  1. User documentation:
    • manuals for end-users of the product
    • manuals for the system administrators.
    • User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.
    • FAQs
    • Video tutorials
    • Embedded assistance
    • Support Portals
  1. Q&A documentation
    • Test strategy
    • Test plan (list of features to be tested, testing methods, timeframes, roles and responsibilities (e.g. unit tests may be performed either by the QA team or by engineers))
    • Test case specifications - a set of detailed actions to verify each feature or functionality of a product.
    • Test checklists -list of tests that should be run at a particular time.

Process documentation

Bottom line:
Maybe we should use more tags for different types of documentation?
#system_documentation
#user_documentation
#process_documentation

This list of user stories is something that can be written in a wiki.
@douardda or do you prefer having this list of scenarios in the docs ( for example in: docs.softwareheritage.org/user-stories)

(sorry I missed your question back then)

I don't know for sure, i guess this is more a question of where in the main index should these stories be "presented"; or what the expected "navigation path" to reach them .