Switch to HTML for generated device documentation #51

Closed
opened 2 years ago by izzy · 3 comments
izzy commented 2 years ago
Owner

Currently, device documentation is generated as Markdown – no specific flavor, to be widely compatible. That restricts formatting quite a bit, which is why Adebar almost completely uses only headers and lists. As a result, there's a lot of scrolling, and information often isn't easy to grasp.

A good idea would be switching to HTML+CSS (no JS, though), which would give a lot of flexibility: tables, coloring/theming, even some responsiveness – plus it can easily be viewed in any web browser, without the need of some "conversion tools".

I took an existing device documentation, stripped the app listings down a bit, and created a mockup (CSS) which even has some responsive parts. Not being a big designer, I'd welcome feedback on this before I start rewriting. I've used classes and ids quite a lot to hopefully make styling easy; if you think there's some id/class missing somewhere, please say so (e.g. each section/table could get its own id, so CSS could even reorder items). Alternative style sheets are welcome, too – after all, they come as separate files, so no need to restict us to a single one; Adebar could even by default ship several.

Looking forward to your feedback and ideas!

Currently, device documentation is generated as Markdown – no specific flavor, to be widely compatible. That restricts formatting quite a bit, which is why Adebar almost completely uses only headers and lists. As a result, there's a lot of scrolling, and information often isn't easy to grasp. A good idea would be switching to HTML+CSS (no JS, though), which would give a lot of flexibility: tables, coloring/theming, even some responsiveness – plus it can easily be viewed in any web browser, without the need of some "conversion tools". I took an existing device documentation, stripped the app listings down a bit, and [created a mockup](https://android.izzysoft.de/misc/adebar.html) ([CSS](https://android.izzysoft.de/misc/adebar.css)) which even has some responsive parts. Not being a big designer, I'd welcome feedback on this before I start rewriting. I've used classes and ids quite a lot to hopefully make styling easy; if you think there's some id/class missing somewhere, please say so (e.g. each section/table could get its own id, so CSS could even reorder items). Alternative style sheets are welcome, too – after all, they come as separate files, so no need to restict us to a single one; Adebar could even by default ship several. Looking forward to your feedback and ideas!
izzy added the
enhancement
help wanted
labels 2 years ago
izzy self-assigned this 2 years ago
Poster
Owner

If you use Adebar, feedback is welcome: first implementation was checked in to the devel branch. Please test if it's working for you and let me know what needs fixing/improving. Already on my list: adding IDs to the tables so you can address them directly via custom CSS.

If you use Adebar, feedback is welcome: first implementation was checked in to the [devel branch](/izzy/Adebar/src/branch/devel). Please test if it's working for you and let me know what needs fixing/improving. Already on my list: adding IDs to the tables so you can address them directly via custom CSS.
Poster
Owner

47a4f4e added IDs to tables. Now I'm looking forward to your feedback – and maybe suggestions to improve the CSS.

47a4f4e added IDs to tables. Now I'm looking forward to your feedback – and maybe suggestions to improve the CSS.
Poster
Owner

Completed at 802a80cab6. Still open for CSS improvements.

Completed at 802a80cab6. Still open for CSS improvements.
izzy closed this issue 2 years ago
Sign in to join this conversation.
No Milestone
No Assignees
1 Participants
Notifications
Due Date

No due date set.

Dependencies

No dependencies set.

Reference: izzy/Adebar#51
Loading…
There is no content yet.