TeX Hour tomorrow: More on Better Technical Documentation
Jonathan Fine <[email protected]> Wed, 16 Mar 2022 14:54:10 +0000
| Newsgroups | gmane.comp.tex.latex.latex3 |
|---|---|
| Message-ID | <CALD=Yf9DKN=68VBvy5F3-Wo996PxZ=z4svNos6ze=VMUq7iMJg@mail.gmail.com> |
--000000000000b6437c05da571608 Content-Type: text/plain; charset="UTF-8" Hi Tomorrow's TeX Hour continues from last month's topic: Better Technical Documentation. Date and time: Thursday 17 March, 6:30 to 7:30pm UK (and UTC) time. UK time now: https://time.is/UK. Zoom URL: https://us02web.zoom.us/j/78551255396?pwd=cHdJN0pTTXRlRCtSd1lCTHpuWmNIUT09 Last month's meeting was based on a "needs discovery" meeting organised by Daniele Procida, who I've met several times at UK Python conferences. Daniele is now one of several Directors of Engineering at Canonical, the developers of Ubuntu Linux, where he has special responsibility for improving both documentation and the process by which it is created. Daniele is now giving 3 weekly 2 hour workshops to research software engineers. Tomorrow's TeX Hour is based on my experience of the first two workshops. Here's my core of last week's workshop. People have different modes of activity. Common modes are sitting, standing and lying. Listening, talking and observing. Common modes related to tools are handling a tool, using a tool, creating a tool and understanding a tool. Software documentation works better when it fits the mode of activity. To be useful, this knowledge must be incorporated into experience and practice. The third and final workshop next week will be on tooling, with a focus on the Sphinx system, which was created especially for the core Python documentation. It's been in use since 2008. The previous system used LaTeX as the input syntax. Sphinx uses the specially developed RST markup language. https://www.sphinx-doc.org/en/master/ Last month's TeX Hour on Better Technical Documentation https://youtu.be/gbBNuUOWF0c Last week's TeX Hour on CLI and text interfaces, Python syntax errors https://youtu.be/E6jXQMRvVcg This week's TeX Hour is: Thursday 17 March, 6:30 to 7:30pm UK (and UTC) time. UK time now: https://time.is/UK. Zoom URL: https://us02web.zoom.us/j/78551255396?pwd=cHdJN0pTTXRlRCtSd1lCTHpuWmNIUT09 with best regards Jonathan --000000000000b6437c05da571608 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div class=3D"gmail_quote"><div dir=3D"ltr"><div class=3D"= gmail_quote"><div dir=3D"ltr"><div class=3D"gmail_quote"><div dir=3D"ltr">H= i</div><div dir=3D"ltr"><br></div><div dir=3D"ltr">Tomorrow's TeX Hour = continues from last month's topic: Better Technical Documentation.</div= ><div dir=3D"ltr"><br></div><div dir=3D"ltr">Date and time: Thursday 17 Mar= ch, 6:30 to 7:30pm UK (and UTC) time.<br>UK time now: <a href=3D"https://ti= me.is/UK" target=3D"_blank">https://time.is/UK</a>.<br>Zoom URL: <a href=3D= "https://us02web.zoom.us/j/78551255396?pwd=3DcHdJN0pTTXRlRCtSd1lCTHpuWmNIUT= 09" target=3D"_blank">https://us02web.zoom.us/j/78551255396?pwd=3DcHdJN0pTT= XRlRCtSd1lCTHpuWmNIUT09</a><br></div><div dir=3D"ltr"><br></div><div dir=3D= "ltr">Last month's meeting was based on a=C2=A0"needs discovery&qu= ot; meeting organised by Daniele Procida, who I've met several times at= UK Python conferences. Daniele is now one of several Directors of Engineer= ing at Canonical, the =C2=A0developers of Ubuntu Linux, where he has specia= l responsibility for improving both documentation and the process by which = it is created.</div><div dir=3D"ltr"><br></div><div>Daniele is now giving 3= weekly 2 hour workshops to research software engineers. Tomorrow's TeX= Hour is based on my experience of the first two workshops. Here's my c= ore of last week's workshop.</div><div><br></div><div>People have diffe= rent modes of activity. Common modes are sitting, standing and lying. Liste= ning, talking and observing. Common modes related to tools are handling a t= ool, using a tool, creating a tool and understanding=C2=A0a tool. Software = documentation works better when it fits the mode of activity. To be useful,= this knowledge must be incorporated into experience and practice.</div><di= v><br></div><div>The third and final workshop next week will be on tooling,= with a focus on the Sphinx system, which was created especially for the co= re Python documentation. It's been in use since 2008. The previous syst= em used LaTeX as the input syntax. Sphinx uses the specially developed RST = markup language.</div><div><a href=3D"https://www.sphinx-doc.org/en/master/= " target=3D"_blank">https://www.sphinx-doc.org/en/master/</a><br></div><div= ><br></div><div>Last month's TeX Hour on Better Technical Documentation= <a href=3D"https://youtu.be/gbBNuUOWF0c" target=3D"_blank">https://youtu.b= e/gbBNuUOWF0c</a></div><div>Last week's TeX Hour on=C2=A0CLI and text i= nterfaces, Python syntax errors=C2=A0<a href=3D"https://youtu.be/E6jXQMRvVc= g" target=3D"_blank">https://youtu.be/E6jXQMRvVcg</a><br></div><div><br></d= iv><div>This week's TeX Hour is: Thursday 17 March, 6:30 to 7:30pm UK (= and UTC) time.</div><div>UK time now: <a href=3D"https://time.is/UK" target= =3D"_blank">https://time.is/UK</a>.<br>Zoom URL: <a href=3D"https://us02web= .zoom.us/j/78551255396?pwd=3DcHdJN0pTTXRlRCtSd1lCTHpuWmNIUT09" target=3D"_b= lank">https://us02web.zoom.us/j/78551255396?pwd=3DcHdJN0pTTXRlRCtSd1lCTHpuW= mNIUT09</a><br></div><div><br></div><div dir=3D"ltr"><div>with best regards= </div><div><br></div><div>Jonathan</div></div> </div></div> </div></div> </div></div> --000000000000b6437c05da571608--