Post AiPnnZRoVLWUly2LQG by overanalytcl@hachyderm.io
(DIR) More posts by overanalytcl@hachyderm.io
(DIR) Post #AiPm245lAOydxaVMzw by thelastpsion@bitbang.social
2024-05-30T11:01:11Z
0 likes, 0 repeats
@overanalytcl @ChampionsLeague You've both mentioned FP docs to me, so... 😁IMO the docs are really difficult for a newbie to use. The structure doesn't make sense to me and I can usually only find things using Google as there's no internal search. Examples of how libraries are used are minimal or non existent. I shouldn't have to switch between the docs, the wiki, and Dephi's docs to find out how to do something.Note that I'm not new to programming. It did get easier, but it's not ideal.
(DIR) Post #AiPmOV7HN3hU96uizA by overanalytcl@hachyderm.io
2024-05-30T11:04:39Z
0 likes, 0 repeats
@thelastpsion @ChampionsLeague I am not sure if you wanted to tag that other account, but anyway:yes, sadly that's the state of affairs currently, I am working on having a functioning FP docs pipeline (as in, replicating the pipeline over on Gitlab so I can generate the same HTML files) and then see what I can do about it, transform that into Markdown (including the User and Programmer Guides) and render it using a nicer theme. 1/2
(DIR) Post #AiPmXtmX2EVrFagt5U by thelastpsion@bitbang.social
2024-05-30T11:06:55Z
0 likes, 0 repeats
@overanalytcl You're right, I didn't! Really don't know how I managed that. It should have been @chainq
(DIR) Post #AiPmed4LZRXNRbEVFY by overanalytcl@hachyderm.io
2024-05-30T11:08:08Z
0 likes, 0 repeats
@thelastpsion edited on my end to tag the right person
(DIR) Post #AiPnG6yhKhtmv4So64 by thelastpsion@bitbang.social
2024-05-30T11:14:56Z
0 likes, 0 repeats
@overanalytcl @chainq It's great to have a wiki. But it needs to be kept on top of, and people need to be willing to make updates. Not all projects can be Arch/Gentoo levels of wiki glory - they have money and people. But it would be great if community members could be encouraged more to help out with docs.I do have a wiki account now, so I'm planning on adding a couple of new pages for my DOS escapades, and fixing up a few pages I've noticed are out of date.
(DIR) Post #AiPnhZpi9tbSEMMB1c by thelastpsion@bitbang.social
2024-05-30T11:19:53Z
0 likes, 0 repeats
@overanalytcl @chainq To me, the Gold Standard language docs is PHP (I wrote a fair amount of PHP back in the mid '00s, so PHP4/5/6). It has search, the structure is clear, concepts are well explained, examples are everywhere, and you can have user-submitted examples which can be voted on. It's backed by git, which has its pros from an admin point of view.I'm personally a fan of AsciiDoc over Markdown. IMO the structure is far better for technical docs. Tooling is good, but not as popular.
(DIR) Post #AiPnnZRoVLWUly2LQG by overanalytcl@hachyderm.io
2024-05-30T11:20:57Z
0 likes, 0 repeats
@thelastpsion @chainq yes, I know it is up to the community to an extent, but that's no excuse to not have a tutorial for your own language... The community as a whole should be more involved in promoting the language, since otherwise we'll suffer the same fate as many other languages. Even Fortran managed to revive and have a modern website, so that's what I am setting up.
(DIR) Post #AiPo7ajRRI0KY0pRh2 by overanalytcl@hachyderm.io
2024-05-30T11:24:34Z
0 likes, 0 repeats
@thelastpsion @chainq I know the PHP docs, I absolutely love them. I should look into how they do their git stuff, now that you mention it, since that would be really useful in my case.I like AsciiDoc too, and thanks to you mentioning that I just discovered Hugo can read .adoc files too (and .org, for that matter, which is really convenient). I wouldn't mind converting to .md, but using adoc directly would be nice.
(DIR) Post #AiPoHTKTohGsU6rfOK by thelastpsion@bitbang.social
2024-05-30T11:26:18Z
0 likes, 0 repeats
@overanalytcl @chainq I was really struggling with some basic concepts before I found Castle Game Engine's Modern Object Pascal Introduction for Programmers. This was perfect for me. https://castle-engine.io/modern_pascal
(DIR) Post #AiPolgcexPiWOsm8GW by overanalytcl@hachyderm.io
2024-05-30T11:31:50Z
0 likes, 0 repeats
@thelastpsion @chainq I also recommend that tutorial, although it would be great if I didn't have to go to a game engine to learn about the language. It is a nicely made tutorial, Michalis put a lot of thought into it (this intro used to be separate). There is a notable lack of an updated tutorial for beginners (this assumes you already know a programming language and it states it upfront).
(DIR) Post #AiPsQwIHtbS8jvboh6 by istvan@noauthority.social
2024-05-30T12:12:56Z
0 likes, 0 repeats
@thelastpsion @overanalytcl @chainq It’s amazing how good their docs are, and how good they have always been.Even back to the days of PHP 3.0 it was basically what you see now.