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

[Faibussowitsch, Jacob]

> I'm concerned that the code is copied in rather than referenced from its
> original source.  I think you modify to use start-at and end-at to
> extract the pieces.

You are correct, that is something Patrick mentioned when showing us the format for the first time, its just a limitation of him throwng together this template. In the finished version it will directly link to source code within the Petsc repo. Currently he has that specific example sitting in the same folder, so we made sure that direct code linking works.

> I don't think it's necessary to discuss every part, but it would be
> useful to have more prose (perhaps with equations/diagrams) between
> blocks.

Fair point, that is something we are trying to gauge from users (how much explanation is too much). Our design philosophy in this case is not to assume any knowledge on the part of the reader of the guide in order to make it as accessible as possible, but of course that should have its limits.

> I'd like for each function to be clickable, like it is in our current
> documentation and in Doxygen.  (We've been chatting about this in
> previous discussion, but haven't found a clean solution.)


Yeah in the finished product Patrick said that every highlighted function would link back to the Petsc manual or man pages, but he said it might require some effort writing a separate sphinx environment for it. Im not very well versed in this part so I’m just paraphrasing from what I remember him telling us in the meeting but that’s the goal.

Ill pass your mail onto the rest of the team, thanks for sharing your thoughts!

Best,

Jacob

> On Aug 16, 2019, at 5:23 PM, Jed Brown <jed at jedbrown.org> wrote:
> 
> FYI, the source for this example is here:
> 
> https://bitbucket.org/psanan/sphinx_scratch/src/master/introductory_tutorial_ksp.rst
> 
> (raw) https://bitbucket.org/psanan/sphinx_scratch/raw/a19b48b61e50181e754becb57fc6ff36d7639005/introductory_tutorial_ksp.rst
> 
> I'm concerned that the code is copied in rather than referenced from its
> original source.  I think you modify to use start-at and end-at to
> extract the pieces.
> 
> I don't think it's necessary to discuss every part, but it would be
> useful to have more prose (perhaps with equations/diagrams) between
> blocks.
> 
> I'd like for each function to be clickable, like it is in our current
> documentation and in Doxygen.  (We've been chatting about this in
> previous discussion, but haven't found a clean solution.)
> 
> "Faibussowitsch, Jacob via petsc-dev" <petsc-dev at mcs.anl.gov> writes:
> 
>> 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