symbolic
symbolic copied to clipboard
gnu-octave
readme: make it easier to get started
Someone wrote to me saying that the examples to get started are in a screen-shot and thus not copy-pastable.
- Should we rename the "How to install" section to "Getting starting"?
- Should we have just one screenshot so its not so far to scroll to the text?
- We could make the step-by-step look more like an example, e.g., showing the output.
- People often have trouble getting Python/SymPy working: maybe we should point people at
sympref diagnosein the README file.
Other ideas?
Question: is the README.md file on Github really the first point of contact? Right now, maybe. But in upcoming 2.8.0, the DESCRIPTION file points the homepage to https://octave.sourceforge.io/symbolic/, and I think the repo link will also point to the sourceforge mirror (this maybe should be changed).
Maybe we should concentrate our efforts on improving https://wiki.octave.org/Symbolic_package
Or maybe we need a manual so that the source-forge page gets a "package documentation" link (e.g., like Octave-Interval already has). This could be a pretty sparse manual to start with, consisting mostly of "Getting Started"... See also #584.
@mtmiller do you have thoughts on this? On one hand, I think Github repo pages are should be focused on developers. OTOH, nobody reads docs so we need prominent "getting started" instructions.
Yeah, my thoughts are that the README should be clear and concise, document as much as necessary but no more. I think a full manual would be ideal, such that the README can point to specific sections on installation, troubleshooting, development, and so on. That's the direction I'm planning on for pythonic.
Does the Interval manual (written in texinfo, with a makefile to build html and pdf) seem like the right approach? I don't need an immediate answer: not going to start a manual today, certainly not one as extensive as Interval.
Idea: the links @mtmiller refers to can point the manual as hosted on Octave-Forge (i.e., sourceforge). Then the manual's section on Development can point back here to Github.com (and Gitlab.com for Pythonic).
For pythonic I am leaning towards Sphinx / reST for the user manual, which will help it look like other Python library manuals, help it be more accessible to new contributors, and can also be rendered into Info format if that is desirable someday.