Documentation improvement

[erichstuder]

Hello

I'm a newbie having a hard time reading the docs (v2.0.0) https://sphinx-needs.readthedocs.io/en/latest/

The documentation starts right away with customization: "You can easily customize the list above via configuration. For instance, you can customize the need objects to support bugs, user stories or features." Feels like moving with light speed to me.

Next there are some examples, but how are they executed? What do the files look like? Who do the files have to look like? Where are the files? (Note: You don't have to answer my questions above. That is just what went through my head at the beginning.) I think for somebody that is already familiar with SPHINX this might be easy. But for a newbie (or at least me) it feels a bit unguided.

Maybe I'm getting something wrong but these are my improvement ideas:

1. Maybe there could be a small project example (or a link to one) at the beginning of the documentation.
2. Provide the code for the examples?

Either way I will understand how this works and I already think it is a great idea.

[twodrops]

Thanks @erichstuder for your feedback. Nice that someone is looking at the documentation with new perspectives. For many who have been using sphinx-needs for the last several years, such usability issues of documentation goes unnoticed. I am sure @danwos will get back with what's possible.

I have seen an effort from @danwos here in the direction of providing reusable code/example: https://sphinx-scale.readthedocs.io/en/latest/

[danwos]

I totally understand the concerns regarding the first steps and there is definitely room for improvements.

In the last weeks I have set up a Sphinx-Needs demo project, you can find it here: https://sphinx-needs-demo.readthedocs.io/

It's not complete, but all sources are available and some Sphinx-Needs feature details get explained. However, it is still not a Beginners-Guide or some kind of a tutorial.

I guess we should add an info-panel to our documentation page. Something like:

New to Sphinx and need a helping hand?
The current documentation covers only the features of Sphinx-Needs. So, some basic Sphinx skills would avoid too much frustration :)

- Sphinx Tutorial A
- Sphinx Tutorial B
- Sphinx Main page.
- docutils page

[chrisjsewell]

I would say this is fixed in https://sphinx-needs.readthedocs.io/en/latest/tutorial.html 😄

but feel free to open a new issue with any additional improvement suggestions