[petsc-dev] Working Group Beginners: Feedback On Layout

[Faibussowitsch, Jacob]

I also think it would be useful to have links to the man pages for specific key functions which are fundamental to the objectives of the tutorial. These could appear at the end of the tutorial under a new section heading (eg "Further reading"). It would be good to keep the list of man pages displayed to a minimum to avoid info overload and obscuring the primary objectives of the tut.

This is a key goal of the tutorials, in that a new user should not be overloaded with too much info but also have to look in 10 different places in order to get all of the information they need. In the finished product every Petsc function in the text will have links to the user manual or man pages. Its not currently working in the example shown due to some limitations in the rst framework were using but it will we working in the final product.

Another key aspect here is that we are also revamping the user manual and bringing it to a bit more prominence than it was before, the idea being that these tutorials show the basics of how to interact with Petsc and get something going, and then have links all over the tutorials keywords that would go to the user manual where there is much more detailed information.

Thank you for sharing your thoughts, I will relay them back to the rest of the team!

Best,

Jacob

On Aug 16, 2019, at 2:02 PM, Dave May <dave.mayhem23 at gmail.com<mailto:dave.mayhem23 at gmail.com>> wrote:

I think it would useful to have links to all the man pages in the table of contents.

I also think it would be useful to have links to the man pages for specific key functions which are fundamental to the objectives of the tutorial. These could appear at the end of the tutorial under a new section heading (eg "Further reading"). It would be good to keep the list of man pages displayed to a minimum to avoid info overload and obscuring the primary objectives of the tut.

Overall I like it. Nice work.

Cheers,
Dave

On Fri, 16 Aug 2019 at 16:22, Faibussowitsch, Jacob via petsc-dev <petsc-dev at mcs.anl.gov<mailto:petsc-dev at mcs.anl.gov>> wrote:
Hello All PETSC Developers/Users!

As many of you may or may not know, PETSc recently held an all-hands strategic meeting to chart the medium term course for the group. As part of this meeting a working group was formed to focus on beginner tutorial guides aimed at bringing new users up to speed on how to program basic to intermediate PETSc scripts. We have just completed a first draft of our template for these guides and would like to ask you all for your feedback!  Any and all feedback would be greatly appreciated, however please limit your feedback to the general layout and structure. The visual presentation of the web page and content is still all a WIP, and is not necessarily representative of the finished product.

That being said, in order to keep the project moving forward we will soft-cap feedback collection by the end of next Friday (August 23) so that we can get started on writing the tutorials and integrating them with the rest of the revamped user-guides. Please email me directly at jfaibussowitsch at anl.gov<mailto:jfaibussowitsch at anl.gov> with your comments! Be sure to include specific details and examples of what you like and don’t like with your mail.

Here is the template:
http://patricksanan.com/temp/_build/html/introductory_tutorial_ksp.html

Sincerely,

Jacob Faibussowitsch


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190816/6bd1332c/attachment-0001.html>