Documenting Plone 6, or how to lead by getting out of the way
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 44 | |
| Author | ||
| Contributors | ||
| License | CC Attribution 3.0 Germany: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor. | |
| Identifiers | 10.5446/60208 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language | ||
| Production Place | Namur, Belgium |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
Plone Conference 202241 / 44
10
14
22
23
26
27
40
00:00
Projective planeComputer-assisted translationMachine visionGoodness of fitComputer animationLecture/Conference
00:25
Data managementEndliche ModelltheorieProjective planeArithmetic meanMeeting/InterviewComputer animationLecture/Conference
01:10
Complex (psychology)Projective planeWebsiteSoftwareSoftware developerINTEGRALComputer animation
01:38
WhiteboardLecture/Conference
02:07
Rule of inferencePhysical lawCore dumpLevel (video gaming)2 (number)Division (mathematics)Game theoryMeeting/Interview
02:37
Slide ruleRule of inferenceGame theoryMeeting/Interview
03:21
Game theoryInsertion lossPhysical lawMereologyMultiplication signView (database)Computer animation
04:08
Plane (geometry)SpacetimeLine (geometry)Multiplication signAxiom of choiceDecision theoryLecture/Conference
04:42
Game theoryDecision theoryAxiom of choiceMultiplication signProcess (computing)Meeting/Interview
05:41
Software developerMatching (graph theory)Hand fanInterior (topology)
06:29
Multiplication signAsynchronous Transfer ModeArithmetic meanProcess (computing)System callDifferent (Kate Ryan album)Point (geometry)Coma BerenicesCycle (graph theory)Dot productOnline helpMeeting/InterviewComputer animationLecture/Conference
07:52
Execution unitProgrammable read-only memoryMultiplication signWordExpert systemElectronic program guideExpected valueFormal languageFormal grammarMeeting/Interview
08:56
Plane (geometry)GoogolFormal grammarLecture/Conference
09:21
CollaborationismProjective planeBitFormal grammarPerfect groupMeeting/Interview
10:00
Wave packetState of matterWeb pageFlow separationRepository (publishing)Computer animation
10:26
Software development kitWeb pageRepository (publishing)Wave packetConnectivity (graph theory)Software developerWritingContinuous integrationMeeting/Interview
11:23
Level (video gaming)Meeting/Interview
11:53
InformationLink (knot theory)Revision controlDecision theorySystem callMeeting/Interview
12:31
Stagnation pointDot productDivisorBit rateSelectivity (electronic)WindowLecture/ConferenceMeeting/Interview
14:09
Unitäre GruppeAsynchronous Transfer ModeCodeLemma (mathematics)Scripting languageJava appletPay televisionWeb pagePlanningContext awarenessComputer animation
14:37
Point (geometry)Module (mathematics)Ordinary differential equationPlot (narrative)Computing platformPlanningSubject indexingTable (information)Disk read-and-write headElectric generatorComputer animationMeeting/Interview
15:07
Plot (narrative)Software developerContent (media)Table (information)CodeBlock (periodic table)File formatLink (knot theory)Disk read-and-write headExtension (kinesiology)Network topologyMedical imagingComputer animation
15:40
Extension (kinesiology)Software developerAuthorizationMeeting/Interview
16:04
Plot (narrative)Dean numberAuthorizationAttribute grammarSampling (statistics)Disk read-and-write headMedical imagingCodeComputer animationMeeting/Interview
16:44
CodeSampling (statistics)Electronic visual displayDirected graphType theory1 (number)GUI widgetTable (information)Meeting/Interview
17:29
Demo (music)Reading (process)Link (knot theory)Multiplication signWeb browserMathematicsMeeting/InterviewComputer animation
18:34
Plane (geometry)Demo (music)Link (knot theory)Forcing (mathematics)Subject indexingDemo (music)Group actionComputer animationMeeting/Interview
19:03
EmailDependent and independent variablesFreewarePoint (geometry)Internet service providerTerm (mathematics)Alphabet (computer science)Latent heatSubject indexingAlpha (investment)Meeting/InterviewComputer animation
19:36
InformationFront and back endsType theoryField (computer science)Term (mathematics)FacebookWebsiteOpen setAdditionGraph (mathematics)Shared memoryMeta elementTwitterLevel (video gaming)Computer animation
20:03
Color managementGreatest elementTwitterINTEGRALContinuous integrationLink (knot theory)Meeting/Interview
20:30
GEDCOMPlane (geometry)Link (knot theory)Graph (mathematics)Web pageProduct (business)Inheritance (object-oriented programming)Online helpVideo gameMeeting/InterviewSource code
21:14
Token ringComputer iconGroup actionControl flowGeneric programmingCodeLink (knot theory)PasswordExtension (kinesiology)GUI widgetPlastikkarteBookmark (World Wide Web)CodeBlock (periodic table)Extension (kinesiology)Web browserMultiplication signText editorLinearization1 (number)Meeting/InterviewComputer animation
22:03
Extension (kinesiology)Presentation of a groupComputer iconTime domainBlock (periodic table)CodeBuildingSample (statistics)Graph (mathematics)Open setModul <Datentyp>System administratorSource codeLink (knot theory)Electronic program guideLetterpress printingVariable (mathematics)Function (mathematics)Installation artPlane (geometry)Software developerComputer-generated imageryFront and back endsDemo (music)Revision controlMultiplication signLinearization1 (number)Installation artTwitterAxiom of choiceBootstrap aggregatingComputer animation
22:41
Token ringControl flowType theoryData typeFinitary relationEmailExtension (kinesiology)CodeSampling (statistics)Dependent and independent variablesComputer animationMeeting/Interview
23:13
Content (media)EmailMenu (computing)Gateway (telecommunications)Algebraic closureString (computer science)Parameter (computer programming)Group actionPlane (geometry)Finitary relationSource codeInterface (computing)Front and back endsInternationalization and localizationModule (mathematics)CodeMultiplicationWebsiteContext awarenessBootingRepresentational state transferInformationSource codeComputer animation
23:38
BootingCurvatureSoftware testingWhiteboardProjective planeTrailSoftware repositoryMultiplication signDemo (music)Coma BerenicesRaw image formatComputer animationMeeting/Interview
24:20
Demo (music)Extension (kinesiology)OvalLink (knot theory)Electronic mailing listSheaf (mathematics)Remote procedure callInterior (topology)
24:44
Link (knot theory)Slide ruleWave packetSheaf (mathematics)Shared memory1 (number)Meeting/Interview
25:24
Computer wormCodeComputer animationMeeting/Interview
25:55
Meeting/Interview
26:41
Hand fanWordMultiplication signLine (geometry)Differenz <Mathematik>
27:34
Line (geometry)Multiplication signDifferenz <Mathematik>Group actionDataflow
28:22
Real numberMultiplication signRight angleWritingProjective plane
29:14
Right angleTime zoneMeeting/Interview
29:41
Personal identification numberPoint (geometry)Multiplication signShared memoryLine (geometry)Sign (mathematics)Type theoryRadical (chemistry)CodeForcing (mathematics)Text editorInformationPerfect groupLecture/ConferenceMeeting/Interview
Transcript: English(auto-generated)
00:01
Please welcome Steve Percy. Steve is a volunteer and contributor in the PyLance project. He is also a CAT Herder for Plon6 documentation, and he will talk all about CAT and Herding. Thank you. Good morning, everyone. I'm really glad to be here.
00:23
My talk today is Plon6 documentation, or how to lead by getting out of the way. My talk today will, this is mostly for anyone who is a team leader or a team contributor, and I want you to notice that I have a very simple model of a team.
00:43
I think too much management gets in the way of doing meaningful work, yet too little management, and by that I mean cultivation, mentoring, and encouragement means contributors drift or feel unappreciated or resentful in quality of work's efforts.
01:08
What will you get out of this talk? And I hope that you'll learn about how to cultivate contributors for complex never-ending projects.
01:21
And you might want to even get and take a working copy of our Plon6 documentation for your own use. And it's like, well, why is that a big deal? Well, if it ain't documented, it's broken. And when you're creating software, that's a really critical thing to have.
01:41
It is definitely a feature. Documentation is marketing. If you are into sales, you need to have good documentation for your developers, your contributors, your integrators, and your end users. Documentation is what you use to onboard new team members and to train end users.
02:03
So it's an excellent tool for that. Now, before I go on much further, here's a fun fact about me. I was a soccer referee for 25 years up to about the second division of professional level of soccer. And that was in the United States.
02:23
The most important thing that the best soccer referees understand and take into their core being is a poetic passage from the laws of the game, which is the soccer rule book.
02:41
And, you know, you say, well, that doesn't make sense. How can a rule book about a game have poetry? Well, but it has it. And that's why it's like, that's pretty profound. And what I found is that this passage is something that not only I can apply,
03:00
but you can apply in everything that you do in your relationships, in your job, and in your own self. And with that, I'll go on to the next slide. And I apologize in advance for the wall of text that you're about to see, but it's okay because it's poetry.
03:21
I'll read this for you if you can't see it. The Spirit of the Game. The laws of the game are intended to provide that games should be played with as little interference as possible. And in this view, it is the duty of the referee to penalize only deliberate breaches of the law.
03:45
Constant whistling for trifling and doubtful breaches produces bad feeling and loss of temper on the part of the players and spoils the pleasure of the spectators. Now, that's something that's profound.
04:03
You would never see that this would ever be written into law. How to not be a jerk, but also how to support the game and the activity that you are all engaged in. So what does that really mean, though? What does this apply to?
04:22
And I've taken it upon myself to think that it means that leaders must create a safe space for professionals to perform at their best. That's an anything. Leaders do not enforce trivial offenses.
04:43
You know, one sentence per line? Eh, forget it. Just write something. Leaders take the time to explain the choices and decisions that have been made. It's a teaching opportunity. With new people coming in, they won't understand the history of why you've made these choices.
05:01
Let's take some time to actually explain that to those folks. And I appreciate the people who have taken that time with me, so I will share that with them. Leaders admit mistakes. It's okay to say, I'm sorry, I messed up. Leaders are always open to learn, to adapt, and to change.
05:22
For example, somebody approaches me with something very complex, and I say, I don't understand. Can you elaborate? I might learn something from you. And then I could take that into my work and do a better job. Leaders also support the team. What can I do to help?
05:44
Always be asking this. What can I do to help you do your work? And lastly, leaders are always present. I'm here for you. And all of these things are the same things that soccer referees do.
06:01
They want to have the most joyful experience so that everybody can be the best that they can in a safe place and challenge themselves to be great and to compete in friendly matches or highly competitive matches. And if you're a soccer fan, you can see how people go crazy over this.
06:24
And some of us use a little more craziness in our Plone development. So I kind of took that and applied it to the spirit of Plone 6 documentation. And we've had contributions to the docs that can drift over time.
06:47
So what we try to do is cultivate and not demotivate. So what I mean by that is that if we have doc contributions that drift toward repetitive reviews
07:02
and never-ending questions and answers, that just gets exhausting and the poll request will die. So we don't want to do that. We want to minimize the review cycles. So sometimes there will be really difficult questions. And so sometimes a quick call or a chat into Discord, now that we have that, which is great.
07:26
It's been super helpful. We can resolve a lot of differences of opinion and start working on the job. We also want to communicate about the process. Why are we doing what we're doing at this point in the game?
07:43
And what do we need to do at this point? What could we do later? So often we'll get a long thing in documentation where we just don't know the answer yet or we're having a really hard time getting the wording just right. We just say, okay, let's put a to-do in there.
08:01
It'll show up in the documentation when it gets published. Somebody who knows better will be able to be the expert wordsmith or know the exact Docker command to use or whatever it is that needs to be put into place. And that does happen a lot. One thing that we also try to do is just as a leader, you try to manage your own expectations.
08:27
And this is extremely, extremely important. For example, it doesn't pay to be too strict about a style guide. And this is especially important for the Plone community
08:40
because most of us don't speak English as our first language. And I certainly don't expect you to be perfect in your English grammar, punctuation, syntax, and all that. It's ridiculous for me to expect that. And I totally get it.
09:02
If you ask me to write something in your language, I will freeze up and do nothing. So what I want people to understand is that if you're more comfortable writing documentation in your primary language, please do that. Submit a pull request.
09:20
We'll run it through Google Translate. And we'll clean up the English grammar and syntax. It might be a little bit funny, but we'll work through it together. Lastly, it's really important in your projects to focus on the collaboration between the people and not perfection. If you start to get into those details, people feel like they're not owners of the documentation anymore.
09:47
They're not owners of the work they produced. And it's like, why are you making me do these things that don't make a whole lot of sense? So we don't do a lot of that kind of stuff.
10:00
So with that, let's get into some of the where we were with the Plone 6 history. With these guiding principles, the documentation team got to work. And that had discussions with Katja, Philip, Kim Paulison, and many, many others. I could list about 50 people that were really involved.
10:20
And first what we did was we defined the state of the Plone documentation. This, in the scope, we decided to find that what we would work on were the things in docs.plone.org, training.plone.org, the front page to the training that's in a separate repository from training,
10:43
the docs for Volto, the docs for Plone.api, and for Plone.restapi. All of those are critical components for Plone documentation. And once we defined the scope, we figured out what are the... We had to assess and evaluate what were the major issues that we had.
11:04
We looked at it and said, our theme is outdated. It's not mobile-friendly. Volto developers, hey, they're using JavaScript. JavaScript developers like to write markdown. They don't like to write restructured text. It's hard, and I agree, it's hard. I don't like writing restructured text that much.
11:22
I prefer markdown. We didn't have continuous integration or delivery. We had one or two people who actually knew how to build the documentation. And now it's completely automated with GitHub workflows. We found that it was put together and cobbled in a way that didn't make a whole lot of sense.
11:43
And it was just kind of thrown together without a lot of thought. There's deep nesting, and it's very hard to find things once they get down to six or seven levels. That was not very easy to access.
12:02
The search was okay, but it didn't provide enough information for you to actually use it and make a decision on what to click. And how to contribute to the documentation was really not clear. It's very hard to navigate through that. Links were getting old.
12:21
There was stuff that was suffering from what I call copy pasta. It's just a bunch of stuff that got copied from year after year after year. Version from 2.4, 2.5, or whatever. 2 to 4 to 5 and so forth. And we never did any curation to make sure that that documentation still worked.
12:42
Yikes. So all of these factors led to what eventually became stagnation. And Plone 6 docs didn't exist until about a year ago. So because of that, we decided, let me just show you as an example.
13:05
In the Plone 5 documentation, what that was. Let's see if I can do this right. Make sure I got that window selected. It's tricky because I am... There we go.
13:23
What? No, that's not it. There we go. Oh, okay. So in the Plone 5 documentation, we had... I seem to have lost my tab. I did lose my tab.
13:49
I did lose my tab. Sorry about that. Let's see if I can just bring that over here. There we go.
14:02
So in this example, the navigation gets very, very, very deep. And it's hard to find where you are. Navigation scrolls with you. If you search for something like contribute, all these things come up.
14:23
But it doesn't really give you much. It just says here's the page title and not any context. So we identified this and a bunch of other problems, and we came up with a plan. And so in that plan... There we go. Let's go back to presentation.
14:41
There we go. So in that plan, we first had to decide on a platform. As I mentioned earlier, we have very strong opinions about restructured text versus markdown.
15:02
And restructured text has... Well, they each have really strong features. With restructured text, we have cross references with automatic heading generation. We have a glossary. We have an index. We have a table of contents. Talk tree, a rich ecosystem of extensions, and it tends to be favored by Python developers.
15:25
And plus, that's what our documentation was originally written in. For markdown, it has some really unique features as well. It's got an easy syntax for headings and links and formatting and code blocks and images, and it's easy to use.
15:41
And it tends to be favored by JavaScript developers. So we debated a while about what would be the best way forward. And about two years ago, this thing came out called Mist. Mist is a rich and extensible flavor of markdown that's meant for technical documentation and publishing.
16:03
It's a... It combines the unique features of both restructured text and markdown, allowing authors to choose whatever syntax that provides what they need. So if it's easier to use markdown for headings, do that.
16:21
If it's easier to use restructured text to have images with various sizes and alt attributes and titles, use restructured text. If you want to have code samples with syntax highlighting, you probably want to use restructured text. You can mix and match. It's wonderful.
16:42
Who wouldn't want to use Mist? So... Yeah. So what we... The next thing that we had to address was that theming issue. And we evaluated various ones, and we found that the one that fit us the best was the Sphinx book theme.
17:02
And this is really cool. It has... There's actually a nice little kitchen sink where you can see a display of all the different widgets, all the typography, all the tables, how you can do layout. And it's very helpful to figure out, oh, that's the thing that I want to see and render, and I have a code sample right there for me.
17:31
So with all that, what happens when leaders do get out of the way? And I wanted to show you...
17:40
Let's see if I can get this over here. An actual demo. It won't work. No, it won't work. Yeah. Okay. I have to skip over the demo thing.
18:00
Technical difficulties. But what we do have are... We can build the documentation with HTML. Live HTML is when you can edit the documentation and have it reload in the browser in the same time. You don't have to build the whole thing at once. It's really nice when you have a little change you want to make, you can see it happen in realtime and make sure that it looks good.
18:27
The third one is link check broken. This was one thing that was missing was doing all these link checks, and I spent probably two days going through all the broken links in the documentation to resolve them and fix them. So now we make that a requirement that thou shalt not publish any broken links in the documentation, and we shall enforce it.
18:47
Yeah, it's not good to have a broken link. The next one... We also have features of... I wanted to also do a demo of what the docs actually have.
19:01
So I can go through that very easily, I hope. Yes. So we have an index. This is something that restructured text provides. Oops, that's a glossary. I'm sorry. We have a glossary which basically has all your terms and defines them. And so in every single one of the documentation, they refer to this glossary, and all the terms are brought into that.
19:27
We have an index. So if you wanted to find a specific term, it's in our index. Alphabetized. And you can click to it and go to that very simple term and find out, oh, what does that mean?
19:41
Okay. What else do we got? We have a site map. So Google likes us. And this is super important to have that. In addition to this site map, now we have meta tags and open graph tags like Facebook stuff and all that.
20:02
So those get populated into tweets and sharing and become more visible to the public when they're trying to search for it. We have... Oh, yeah. Automatic continuous integration and deployment. So now when we get a...
20:22
When we merge a pull request, it gets up there within a few minutes. That was super awesome. Thank you, Errico. This is... We have... Oh, yes. We also have Netlify. So if we go and visit a link of something, we actually have a live preview of a...
20:46
So this graph is actually rendered in that page. And this has not been deployed yet. It's still being under review. But this is not in production. This is on a live preview in a pull request using Netlify.
21:02
This is awesome because now you don't have to go and download and build the docs yourself. You can just look at it and make a comment back in the pull request. So this is super, super duper helpful. And it's free. Thank you, Netlify. We have a storybook.
21:22
So if you go to the 6.dev... Well, I can't remember it. Anyway, it's in my bookmarks. And at append storybook, you'll see all the various widgets that are provided by Volto. And so if you wanted to try them out, grab a code snippet, it's right there.
21:43
What else do we have? Oh, hey, we have code blocks that you can actually just click the copy-paste button. And now you can paste that code into your browser. This is awesome for... Or not your browser, but your code editor. And you can edit away on that.
22:01
Extensions galore. We have tons of things here. I don't have time to go into them. But check them out. One of the cool ones is this. Sphinx design. Where you can have an awesome layout where, hey, we were just struggling. Do we have a linear workflow for things?
22:21
So we say no, not for this. When you have to make a decision about whether I want to try a demonstration or install something, I want to be presented visually with that as a choice. So now we can do some really cool design. And we can have buttons and a bunch of other things that you get from Twitter Bootstrap. What else do we got here?
22:41
I'm so excited. Why did I have this? Oh, I think I just clicked something to go there, and that's what I did. Oh, no, no. This is another awesome extension for the REST API, I believe,
23:00
where you can get various samples of code to use to implement when you're trying to figure out what is the request I want to send and what response should I expect back. This is really cool. Yay. Thank you, REST API peoples. We have autodoc, autosummary, and codesourcing.
23:23
So if I wanted to get more information about a specific method, I have that method. And, hey, I wonder what actually says, what does it say in its source code? I'll go and view the source code. Ooh, isn't that cool? So this is like another Sphinx thing and restructured text
23:41
working together with Markdown. I'm so excited. What else do we got? Oh, we got issues. But we have a huge project board that now is tracking across all the repos that we touch. And I think we're up to maybe six, seven repos now.
24:02
And we're keeping track of how fast we're working through these. We have a burn graph, which shows that we had some time off during the summer and so it was a little bit slow. But now leading up to PloneConf, it's been taken off. And it's going to go through the roof.
24:22
So that was the Plone 6 demo. What else do we got coming up? Oh, let's see. I went too fast. So here's a list of a lot of the extensions that I mentioned with some of those things, like the autodoc.
24:41
Inner Sphinx is the magic that allows you to add a link from one section of a Sphinx doc to another remote section of a Sphinx doc. So we're able to have the training link back to the documentation and vice versa. It's awesome that these things can now be interconnected
25:03
and we're going to keep doing that. And I think I went through most of the other ones. The to-do is really nice because now if you're stuck, just throw a to-do in there. And with that, I'm just going to say I have a couple of references in my slides and I'll share that with the conference after we're done.
25:26
And with that, I just wanted to say thank you very much for allowing me to herd you, my kitties. And I look forward to seeing you come to the Sprint this weekend for documentation.
25:42
If you've never been to a Sprint, it's where you just come out and say, hey, I want to write some code. I want to contribute to the documentation. And I will be more than happy to welcome you. Thank you.
26:06
I'd be happy to answer questions, concerns, gripes.
26:30
You have a question? Yes.
27:16
I want to agree with that wholeheartedly. I am a big fan of the one sentence per line requirement.
27:27
It's a guideline. And there's another reason as well. Trying to do diffs and then reformatting. Well, we don't like to do like the 80 characters per line thing. That's not good because any time you add a word,
27:42
you have to rewrap the whole paragraph and then you have a bunch of useless diff. So one sentence per line is good because you avoid that kind of rewrapping stuff. However, there's also people who are reluctant to do that because when they're writing documentation, that's not in their workflow.
28:04
They just don't want to do it or refuse to do it or just are not able to. And I say, that's fine. I will accommodate you, make your poll request. When you're done, I'll do it one sentence per line for you. I'm more than happy to do that.
28:21
Does it work? No? Yes? Sadly, we have no time left. Maybe a quick question, real quick? Yeah, in the workflow, you lose yours when you are writing.
28:55
So I would kind of suggest maybe put some post coming thing
29:01
that takes that for you or that the human doesn't have to care about that. I don't know if you couldn't. So it could be like a black thing that you're writing. Exactly. So you say that it happened. But when you're writing, I find that just...
29:23
You don't want to get out of your zone. You want to keep flying.
29:53
Steve actually provided with a license for JetBrains. I'm using it.
30:04
Yeah, that's another good point, is that folks were using more of the terminal type editors instead of Pyterm or VS Studio, VS Code, which doesn't have the soft wrap. So all you see is a dollar sign at the end of the line,
30:23
and that's a terrible thing to navigate as an editor. So I feel for you. So I don't enforce it, because I understand that, hey, you're giving your time to give us information and share it, and that is so much more important than being perfect.
30:45
I have a great... Perfection is something that you do if you don't have anything else to do. Sadly, we really have no time left. So thank you, everyone. Thank you, everybody.