docs: Improve docs on publishing Actors and move README topic - #2801
docs: Improve docs on publishing Actors and move README topic#2801szaganek wants to merge 4 commits into
Conversation
szaganek
added
documentation
|
✅ Preview for this PR (commit |
honzajavorek
left a comment
honzajavorek
left a comment
There was a problem hiding this comment.
I didn't notice this PR is just about moving the pages, and I started reviewing the content. I noticed it before I got to "Publish your Actor", so I didn't review that one.
Feel free to ignore my comments, as they're not relevant to the changes you made (moving files around). But if I was to write a summary of my comments here, I'd say that I found no massive issues with the content, but:
- It mostly ignores the fact we're living with AI assistants and AI search now,
- and IMHO it jumps up and down in expectations from the reader. It's not clear if the audience is someone who just saw Markdown for the first time and learns about what README is, and needs some hand-holding, or if the audience is someone more seasoned who we just supply with ideas and links and they're good to go. This is the main weakness of the document.
I also posted several ideas on improvements.
|
|
||
| - Explain in two or three sentences what the Actor does and the easiest way to try it. Mention the goals that the tool helps the user achieve. Describe the input. To grab user's attention, highlight the most important words in bold. | ||
| - List the Actor's main features and platform advantages. | ||
| - If it's a bundle, mention the steps that the Actor takes, and the obstacles it can overcome. Say upfront how many results users can get for free. |
There was a problem hiding this comment.
What is a bundle, in the context of Apify? I use Apify but I don't know how to evaluate "if it's a bundle".
There was a problem hiding this comment.
When reading further, in the ### Pricing section I understand now that this is a way of paying for an Actor 🤔 While "pay per usage" and "price per result" are self-explanatory, the "bundle" mention got me confused. But it could be just me. Someone who has created an Actor and is writing a README for it probably knows these terms and doesn't need an extra hint. Leaving up to you, feel free to ignore this one.
|
|
||
| Consider making images clickable. You can lead such clicks towards a signup page, which is possible with Markdown. | ||
|
|
||
| If your images are too big or occupy too much space, make them smaller with HTML. |
There was a problem hiding this comment.
This advice is ambiguous and for people who don't know a difference between display size of an image and resampling of an image it might be a bit misleading. We should somehow distinguish between "the image stretches too wide in my document, so let's limit it with HTML" and "the image has 20 megabytes or is 6500px wide, and I need a tool to cut the size down"
Co-authored-by: Honza Javorek <[email protected]>
|
Thanks, @honzajavorek, great ideas for improvements! I implemented most of your comments. Re: not-so-well-defined target audience, it's a problem throughout the docs at the moment. Hopefully the ongoing product changes will give us some pointers soon. |
3 participants
Closes #2623.