Development Handbook migration

[marcuspollio]

As part of the website migration, the Dev handbook will be migrated as one of the top-level Sections, grouped under the Documentation navigation entry.

Its content will come mostly from the existing Dev Handbook repository, but may be re-structured and tweaked to better fit its new host (i.e. the new unified website). Initially, its content will be English-only.

Contributors have expressed interest in helping, reviewing, updating, and eventually refactoring this dev section.
So this task aims to gather all advancements in this area under one place.

Potential sub-tasks (subject to change):

• Migrate Docs section index
• Migrate User manual section index with redirect alias to wiki user hub
• Migrate Reference section index with redirect alias to source doc
• Migrate Dev handbook index and structure with following sections:
  • addons: all about addons development
  • code: best practices, review process, copyright, formatting, Python, C++, etc.
  • design: UI/UX, principles, glossary, naming, elements, zones, hints, branding, etc.
  • docs-writing: all about technical and documentation writing
  • infra: all about infrastructure maintenance
  • intro: how to get started contributing (i.e. What can I do for FreeCAD?)
  • roadmap: development goals
  • setup: how to set up you dev environment, build, workflow, submit changes, dependencies management
  • teams: various teams, contact and processes
  • tech: all technical stuff, code architecture, tools, release process, low-level stuff, etc.
  • translate: how to translate FreeCAD, other places, and coordinate with translators
  • web: all about web development, guidelines, and maintenance

[marcuspollio]

@PhoneDroid @mnesarco
Open to discuss how you want to integrate any addons-related stuff (e.g. Addon-Academy, Addon-Reports, etc). Just linked, as a module, or directly inside here, also which structure and content you want, etc. I have not put much though yet on the addons matter, but can give pointer if needed. Thanks!

@senft-research @YosypC
Please feel free to expose your ideas here, about the structure, content, if some custom templates could help, etc.
Recently at a Linux conference, I had a chat with people of the Document Foundation (behind LibreOffice). Among others, they have adopted a somewhat call to action for their newcomers/contributors on-boarding, based on a previous setup by Mozilla: What can I do for LibreOffice?.
For the intro page that is the first when entering the Dev section, having something in that spirit could help get around.
We could easily pull a few dozen items/topics grouped either by bite-size/time commitment (<30 min, a few hours, long-term), area (design & UX, docs, QA, community & support, code, infra, etc), skill level, interests, existing/new/maintain type, field/domain (core, workbenches, scripting, etc).
A sort of easy and playful wizard to get started. It could be quite simple yet effective if well designed.
What do you think?

[PhoneDroid]

@marcuspollio The addon repos will only be linked or embedded.

On the website itself I'd want a top level link to an addons
overview page, that can be in the website repo but I need to
be able to edit the content at any time.

On there I'd link the things I've listed on this overview.

[PhoneDroid]

@marcuspollio If you have some time I'd like
to talk about it in a Jitsi call ( or other ).

[marcuspollio]

@PhoneDroid
Hi! The initial idea I had on how addons-related stuff could be displayed on the website is:

• the primary purpose is to simply inform regular users (i.e. people downloading FreeCAD via the website and/or new to the project) about the add-ons concept, the ones available in FreeCAD and what they consist of. This would be a single page accessible directly from the download or community sections with a list of current add-ons and some metadata (similar to the current addons page).

Something along the lines of:

• the second one is more focused on contributors and would probably go into the dev section (hence the mention in the OP). So here it is still quite open. It could be exactly the content of the Addon-Academy repo linked as a module if it is more convenient (it would just need some minor tweaks), or something else. Let me know what you think?

• yeah, we could setup a Jitsi call soon. I could be available from week 18th (Monday 27th April), preferably around 5-6pm CEST. What about you?

[PhoneDroid]

@marcuspollio Just propose a call time and give me the relative time
to an existing meeting, like 2h after the FPA meeting or something.

As long as it's not overlaping with any of the existing meetings I'd be available.

The current addons page is not desirable.
The addon report - while in report format - is much more usable, something
based on it would be better, I'd imagine Frank will go about that at a later point.

Addon authors != FreeCAD contributors, while a few have contributed
to core, most are standalone developers that work on Their own
project, nor do all of them even want or can be in the official index.

We will have to talk about it, but I don't see it being a sub point on those
2 entries as being the appropriate thing, I'd rather see a top level navigation
point named Addon linking to the overview with sub point like Index, Academy,
Template, ..

[senft-research]

@PhoneDroid @mnesarco
Open to discuss how you want to integrate any addons-related stuff (e.g. Addon-Academy, Addon-Reports, etc). Just linked, as a module, or directly inside here, also which structure and content you want, etc. I have not put much though yet on the addons matter, but can give pointer if needed. Thanks!

@senft-research @YosypC
Please feel free to expose your ideas here, about the structure, content, if some custom templates could help, etc.
Recently at a Linux conference, I had a chat with people of the Document Foundation (behind LibreOffice). Among others, they have adopted a somewhat call to action for their newcomers/contributors on-boarding, based on a previous setup by Mozilla: What can I do for LibreOffice?.
For the intro page that is the first when entering the Dev section, having something in that spirit could help get around.
We could easily pull a few dozen items/topics grouped either by bite-size/time commitment (<30 min, a few hours, long-term), area (design & UX, docs, QA, community & support, code, infra, etc), skill level, interests, existing/new/maintain type, field/domain (core, workbenches, scripting, etc).
A sort of easy and playful wizard to get started. It could be quite simple yet effective if well designed.
What do you think?

I think what was discussed at the dev meeting was to do a full review of the handbook first, with new and experienced developers input on the review, and then structure a new handbook bit by bit whilst getting it approved 1 PR at a time by reviewers of, once again, experienced / newer developers together with equal say.

Hope that clarifies the stance of those whom proposed a refactor for the hand book pal!

[hyarion]

I'm sorry but I think this approach will not work.
The development handbook is a living document that will have to get updated as we go. If you want your website to be the single source of truth you'd have to lock the other down and point to this website instead or accept that it will update and either bring over the changes manually or ignore them. Since the velocity of his website project isn't super fast I think the documentation will diverge quite quickly.

I believe the best option will be to either rework it at the current location and then migrate it with a single click when the website is about to be released, or migrate it as is and then rework it.

[marcuspollio]

Hi @senft-research @hyarion
Thanks for chiming in. I will try to clarify again a few aspects. Let me know if it still not clear.

this approach will not work

Which approach do you refer to?
Do you refer to what Jordan wrote above, i.e. "structure a new handbook bit by bit whilst getting it approved 1 PR at a time", or the "take what we currently have, make the few necessary tweaks so it is compatible, and improve from there" of this new unified website (i.e. mine)? While far from perfect, the second approach allows to have a tangible base for discussions and improvements.

the development handbook is a living document

Yes indeed! Hence the reason for using modules (i.e. a Hugo feature, similar to the git one, that lets you pull any content you want from any source, into the build process). We could even have the dev handbook in a sub-dir of FreeCAD/FreeCAD, it works too. Personally I do not really care where some sections content files are. In this repo, or in another one, as long as the piping and workflow goes smoothly. Some minor adjustments will need to be done, but nothing major.

the website is the single source of truth

Yes, it is exactly the plan for user/visitors. But under the hood, it is a bit more nuanced and complex. I can give more details if needed.

rework it at the current location

Yeah, it is what I suggested many times: start small, on an area that really interests you, maybe with a larger idea in a corner of your mind, and if possible, discuss and submit draft work early and often. Then see how it goes and adapt from there. If help is needed to "adapt" the current repo structure and formatting to be more compatible with the website project here, no worries, that can be easily done, by me or someone else.

So, how shall we move forward?
Maybe we could go into a bit more detail, since I feel like our discussions so far tend to be rather surface-level (aside from @YosypC notes).

What about an online chat on Tuesday 5th May at 6pm CEST (2 hours after addons meetup)? Any other date or time?
I will share a list of points to discuss the week before.

[hyarion]

Which approach do you refer to?

To clarify I mean your approach

[marcuspollio]

Could you explain why and how that could be fixed?